uv

Introduction

uv is a fast, modern Python package and project manager written in Rust. It replaces pip, venv, and in many cases pip-tools, running significantly faster than any of them. It is rapidly becoming the standard tool in professional Python projects.

Installing uv

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify:

uv --version

Creating a Project

uv init my-project
cd my-project

This creates a project directory with a pyproject.toml, a .python-version file, and a starter main.py.

Managing Python Versions

One of uv's most useful features — it can download and manage Python versions for you.

# Install a specific Python version
uv python install 3.12

# Pin the project to a specific version
uv python pin 3.12

Adding Packages

# Add a package (creates/updates .venv automatically)
uv add requests
uv add pandas polars

# Add a development-only package
uv add --dev pytest black

# Remove a package
uv remove requests

uv add automatically updates pyproject.toml and uv.lock.

Running Scripts

# Run a script using the project's environment
uv run main.py

# Run a tool without installing it permanently
uv run --with black black my_script.py

Syncing the Environment

After cloning a project or pulling changes:

uv sync

This installs all dependencies from uv.lock exactly, ensuring everyone on the team has the same environment.

uv vs pip + venv

Task	pip + venv	uv
Create environment	python -m venv .venv	uv init or uv sync
Install package	pip install requests	uv add requests
Install from file	pip install -r requirements.txt	uv sync
Speed	Baseline	10–100× faster
Lock file	Manual (pip freeze)	Automatic (uv.lock)

Practice Exercises

• Install uv and verify the version.
• Create a new project with uv init. Inspect the generated pyproject.toml.
• Add requests and pytest to the project. Check that pyproject.toml reflects both.
• Run uv run main.py to confirm the project environment works.
• Run uv sync in a cloned project (or after deleting .venv) and confirm the environment is restored.